Add comprehensive comments to all source files and expand documentation

config.py

@@ -1,29 +1,61 @@
+"""
+config.py
+=========
+Configuration object loaded by Flask from environment variables.
+
+The application expects values to be provided via Portainer environment
+variables or a local .env file during development.
+
+All values have sensible defaults where safe, but the following MUST be
+set in production:
+  - APP_SECRET_KEY
+  - ADMIN_PASSWORD
+  - SMTP_PASS
+  - PUBLIC_BASE_URL
+"""
+
 import os
 from dotenv import load_dotenv
 
+# Load variables from .env file if present (development mode).
 load_dotenv()
 
+
 class Config:
+    # Flask secret key: used to sign session cookies. Must be a long random string in production.
     SECRET_KEY = os.environ.get('APP_SECRET_KEY', 'dev-secret-change-me')
+
+    # SQLite database path inside the container.
     DATABASE = os.environ.get('DATABASE', '/app/data/booth.db')
+
+    # Directory where uploaded MP3 files are stored inside the container.
     UPLOAD_FOLDER = os.environ.get('UPLOAD_FOLDER', '/app/uploads')
+
+    # Only MP3 uploads are allowed.
     ALLOWED_EXTENSIONS = {'mp3'}
 
+    # SMTP server settings for sending customer emails.
     SMTP_HOST = os.environ.get('SMTP_HOST', 'mailroot8.namespro.ca')
     SMTP_PORT = int(os.environ.get('SMTP_PORT', '465'))
     SMTP_USER = os.environ.get('SMTP_USER', 'ai@hallsworth.ca')
     SMTP_PASS = os.environ.get('SMTP_PASS', '')
     SMTP_FROM = os.environ.get('SMTP_FROM', 'ai@hallsworth.ca')
 
+    # Admin login password (plain text, set via env).
     ADMIN_PASSWORD = os.environ.get('ADMIN_PASSWORD', '')
+
+    # Optional operator alert email. Currently unused because the dashboard is the queue.
     ADMIN_ALERT_EMAIL = os.environ.get('ADMIN_ALERT_EMAIL', '')
 
+    # Public HTTPS URL used in customer emails and QR codes.
     PUBLIC_BASE_URL = os.environ.get('PUBLIC_BASE_URL', 'http://127.0.0.1:5000')
+
+    # Booth name used in email sign-offs.
     BOOTH_NAME = os.environ.get('BOOTH_NAME', 'Trollgorithm Theme Songs')
 
-    # Port the container listens on internally (gunicorn)
+    # Internal port gunicorn listens on inside the container.
     INTERNAL_PORT = int(os.environ.get('INTERNAL_PORT', '8000'))
 
-    # Price settings (informational, for receipt page)
+    # Price per version shown on the receipt page (informational only; payment is manual).
     PRICE_PER_VERSION = float(os.environ.get('PRICE_PER_VERSION', '10.00'))
     CURRENCY = os.environ.get('CURRENCY', 'CAD')