Add inline comments and update README for MusicGPT workflow

app.py

@@ -308,6 +308,10 @@ def musicgpt_webhook():
         req = dict(row)
 
         # Determine which version this webhook belongs to.
+        # MusicGPT sends a separate webhook for each conversion_id; version A is the
+        # first conversion queued and version B is the second. We store both IDs on
+        # the request so we can route the payload correctly and decide which file to
+        # overwrite when a later webhook arrives for the same version.
         version = None
         if req.get('musicgpt_conversion_id_1') and conversion_id == req['musicgpt_conversion_id_1']:
             version = 'A'
@@ -381,7 +385,15 @@ def musicgpt_webhook():
 
 @app.route('/admin/musicgpt/autopoll', methods=['POST'])
 def admin_musicgpt_autopoll():
-    """Internal endpoint used by the cron job. Only runs refresh if auto-poll is enabled."""
+    """
+    Internal endpoint used by the cron job for automatic MusicGPT polling.
+
+    Unlike the manual dashboard refresh endpoint, this route first checks the
+    'musicgpt_autopoll' runtime setting. If automatic polling is disabled it
+    returns immediately without touching the MusicGPT API, so operators can
+    turn background automation on/off from /admin/settings without stopping
+    the cron job.
+    """
     redir = require_admin()
     if redir:
         return redir
@@ -392,7 +404,12 @@ def admin_musicgpt_autopoll():
 
 @app.route('/admin/musicgpt/refresh', methods=['POST'])
 def admin_musicgpt_refresh():
-    """Manual dashboard action: poll all in-flight MusicGPT tasks and update statuses."""
+    """
+    Manual dashboard action: poll all in-flight MusicGPT tasks and update statuses.
+
+    This is intentionally separate from /admin/musicgpt/autopoll so operators can
+    always trigger a manual refresh even when automatic polling is disabled.
+    """
     redir = require_admin()
     if redir:
         return redir
@@ -423,7 +440,7 @@ def admin_musicgpt_refresh():
                 update_request(row['id'], **fields)
             updated += 1
         elif status in ('FAILED', 'ERROR'):
-            update_request(row['id'], musicgpt_status='FAILED', musicgpt_error=conversion.get('status_msg') or 'Polling reported failure')
+            update_request(row['id'], musicgpt_status='FAILED', musicgpt_error=(conversion.get('status_msg') if isinstance(conversion, dict) else None) or 'Polling reported failure')
             failed += 1
         elif status:
             update_request(row['id'], musicgpt_status=status)
@@ -434,7 +451,12 @@ def admin_musicgpt_refresh():
 
 @app.route('/admin/musicgpt/poll/<int:rid>', methods=['POST'])
 def admin_musicgpt_poll_request(rid):
-    """Poll a single MusicGPT task from the admin request page and download files if ready."""
+    """
+    Poll a single MusicGPT task from the admin request page and download files if ready.
+
+    This gives operators a way to force-update one request without waiting for the
+    dashboard refresh or the automatic background poll.
+    """
     redir = require_admin()
     if redir:
         return redir