Add inline comments and update README for MusicGPT workflow

models.py

@@ -10,6 +10,8 @@ Schema overview (see SCHEMA constant):
 - requests table stores customer data, generated prompts, file paths,
   approval state, email timestamps, payment reference, player token,
   vocal gender preference, revision count, revision note, and operator notes.
+- MusicGPT integration fields store task/conversion IDs, status, cost, error,
+  album cover URL, WAV paths, and stems task/cost/URL.
 - Revisions: when a customer requests changes, the current A/B MP3 files are
   renamed to archived "RevN-" copies and new versions are uploaded later.
 - operator_notes is an internal column for the booth team and is never shown
@@ -54,21 +56,21 @@ CREATE TABLE IF NOT EXISTS requests (
     operator_notes TEXT,
     stems_link TEXT,
     stems_interest INTEGER DEFAULT 0,
-    musicgpt_task_id TEXT,
-    musicgpt_conversion_id_1 TEXT,
-    musicgpt_conversion_id_2 TEXT,
-    musicgpt_status TEXT,
-    musicgpt_cost REAL,
-    musicgpt_error TEXT,
-    album_cover_url TEXT,
-    song_a_wav_path TEXT,
-    song_b_wav_path TEXT,
-    deliver_wav INTEGER DEFAULT 0,
-    stems_task_id TEXT,
-    stems_status TEXT,
-    stems_cost REAL,
-    stems_url TEXT,
-    stems_error TEXT
+    musicgpt_task_id TEXT,           -- MusicGPT Music AI task ID shared by Version A and B
+    musicgpt_conversion_id_1 TEXT,   -- conversion ID for Version A
+    musicgpt_conversion_id_2 TEXT,   -- conversion ID for Version B
+    musicgpt_status TEXT,            -- IN_QUEUE / IN_PROGRESS / COMPLETED / FAILED
+    musicgpt_cost REAL,              -- API-reported cost in USD credits
+    musicgpt_error TEXT,             -- error message from MusicGPT or polling
+    album_cover_url TEXT,            -- URL to generated album cover image
+    song_a_wav_path TEXT,            -- local path to Version A WAV (if deliver_wav)
+    song_b_wav_path TEXT,            -- local path to Version B WAV (if deliver_wav)
+    deliver_wav INTEGER DEFAULT 0,     -- 1 if WAV files should be delivered with MP3s
+    stems_task_id TEXT,              -- MusicGPT Extraction task ID for optional stems
+    stems_status TEXT,               -- status of the Extraction job
+    stems_cost REAL,                 -- API-reported stems cost in USD credits
+    stems_url TEXT,                  -- download / share link for stems
+    stems_error TEXT                 -- error message from stems job
 );
 
 CREATE INDEX IF NOT EXISTS idx_requests_status ON requests(status);