documentation and env changes

src/Command/SeedDemoAlbumsCommand.php

@@ -20,6 +20,13 @@ use Symfony\Component\Console\Style\SymfonyStyle;
     name: 'app:seed-demo-albums',
     description: 'Create demo albums with randomized metadata for local development.'
 )]
+/**
+ * Seeds the database with synthetic user-sourced albums.
+ *
+ * - Always marked as "user" source with a unique localId.
+ * - Include randomized names, artists, genres, release dates, and cover URLs.
+ * - Optionally link to existing users as creators when --attach-users is set.
+ */
 class SeedDemoAlbumsCommand extends Command
 {
     private const GENRES = [
@@ -59,11 +66,14 @@ class SeedDemoAlbumsCommand extends Command
         $users = $attachUsers ? $this->userRepository->findAll() : [];
 
         $created = 0;
+        // Track generated localIds so we never attempt to persist obvious duplicates.
         $seenLocalIds = [];
 
         while ($created < $count) {
+            // Generate a localId that is unique in-memory and in the database to avoid constraint violations.
             $localId = $this->generateLocalId();
             if (isset($seenLocalIds[$localId]) || $this->albumRepository->findOneBy(['localId' => $localId]) !== null) {
+                // Only accept IDs that are unique both in-memory and in the DB to avoid constraint errors.
                 continue;
             }