Add comprehensive comments to all source files and expand documentation

Dockerfile

@@ -1,24 +1,42 @@
+# Dockerfile
+# ==========
+#
+# Builds the Theme Song Booth Flask app into a small production container.
+#
+# Steps:
+# 1. Use Python 3.12 slim base image.
+# 2. Install ffmpeg (used only if we later process audio metadata; harmless otherwise).
+# 3. Install Python dependencies from requirements.txt.
+# 4. Copy the entire repo into /app.
+# 5. Create an unprivileged user (boothuser) and data/upload directories.
+# 6. Expose the default internal port and run gunicorn on $INTERNAL_PORT.
+
 FROM python:3.12-slim
 
 WORKDIR /app
 
+# Install ffmpeg; clean apt cache to keep image small.
 RUN apt-get update \
     && apt-get install -y --no-install-recommends ffmpeg \
     && rm -rf /var/lib/apt/lists/*
 
+# Install Python requirements first for layer caching.
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
+# Copy application source, templates, static files, etc.
 COPY . .
 
+# Avoid writing .pyc files and ensure stdout is unbuffered.
 ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONUNBUFFERED=1
 
+# Create a non-root user, persistent directories, and fix ownership.
 RUN useradd -m -u 1000 boothuser && mkdir -p /app/data /app/uploads && chown -R boothuser:boothuser /app
 USER boothuser
 
-# Default internal port; override with INTERNAL_PORT env var
+# Default internal port; override with INTERNAL_PORT env var.
 EXPOSE 8000
 
-# Use shell form so environment variables are expanded at runtime
+# Use shell form so environment variables are expanded at runtime.
 CMD gunicorn -b 0.0.0.0:${INTERNAL_PORT:-8000} --access-logfile - app:app