Add inline comments and update README for MusicGPT workflow

helpers.py

@@ -342,19 +342,19 @@ def get_musicgpt_api_key():
 
 
 def get_musicgpt_default_model():
-    """Return the configured default MusicGPT model."""
+    """Return the configured default MusicGPT model, falling back to a supported model."""
     default = current_app.config.get('MUSICGPT_DEFAULT_MODEL', 'v6-pro')
     models = get_musicgpt_models()
     return default if default in models else models[-1]
 
 
 def get_musicgpt_models():
-    """Return the list of supported MusicGPT models."""
+    """Return the list of supported MusicGPT models (filtered by API key capability)."""
     return list(current_app.config.get('MUSICGPT_MODELS', ['v6', 'v6-pro']))
 
 
 def build_musicgpt_webhook_url():
-    """Build the public webhook URL for MusicGPT async callbacks."""
+    """Build the public webhook URL for MusicGPT async callbacks from PUBLIC_BASE_URL."""
     base = current_app.config.get('PUBLIC_BASE_URL', '').rstrip('/')
     return f"{base}/api/musicgpt/webhook"
 
@@ -539,6 +539,11 @@ def set_musicgpt_autopoll_enabled(enabled):
     cfg['musicgpt_autopoll'] = bool(enabled)
     save_booth_settings(cfg)
 
+
+# ---------------------------------------------------------------------------
+# MusicGPT API client
+# ---------------------------------------------------------------------------
+
 MUSICGPT_API_BASE = "https://api.musicgpt.com/api/public"
 
 
@@ -587,6 +592,9 @@ def musicgpt_generate_request(rid, title, music_style, lyrics, gender=None, mode
 def musicgpt_poll_status(task_id):
     """
     Poll the MusicGPT API for a generation task status.
+
+    MusicGPT's /v1/byId endpoint returns the whole task record, including the
+    'conversion' object with the current status and any available audio URLs.
     Returns a dict with keys: status, message, conversion, or error.
     """
     url = f"{MUSICGPT_API_BASE}/v1/byId"
@@ -640,6 +648,12 @@ def _download_file(url, dest):
 def download_musicgpt_outputs(req, data, version=None):
     """
     Download the MP3 and WAV outputs from a completed MusicGPT webhook/poll payload.
+
+    MusicGPT returns audio URLs under different keys depending on whether the
+    payload is for one conversion or the combined task result. This function
+    normalizes those keys, downloads each available file to the request upload
+    directory, applies MP3 metadata tags, and updates the request row.
+
     Updates the request row with local paths and returns a dict of saved paths.
     `data` is the conversion dict from the API. For per-conversion webhooks,
     pass `version='A' or 'B'`. For combined payloads, version is auto-detected
@@ -650,7 +664,7 @@ def download_musicgpt_outputs(req, data, version=None):
     song_title = req.get("suno_title") or req.get("title")
     saved = {}
 
-    # Map version label to field names.
+    # Map version label to the database column names used to store local paths.
     def _fields(v):
         return ("song_a_path", "song_a_wav_path") if v == "A" else ("song_b_path", "song_b_wav_path")
 
@@ -674,6 +688,9 @@ def download_musicgpt_outputs(req, data, version=None):
         url_key = "conversion_path_1" if v == "A" else "conversion_path_2"
         wav_key = "conversion_path_wav_1" if v == "A" else "conversion_path_wav_2"
         # Also support per-conversion webhook keys without _1/_2 suffix.
+        # When MusicGPT sends one webhook per conversion it usually uses the plain
+        # 'conversion_path' / 'conversion_path_wav' keys; we still need to know
+        # whether to treat it as version A or B. The caller-provided version helps.
         if not (data.get(url_key) or data.get(wav_key)):
             if v == "A" or version == "A":
                 mp3_url = data.get("conversion_path")