Enrich full codebase with architectural Arabic docblocks and synchronize database_schema.sql with live database

backend/app/Controllers/VideoController.php

@@ -1,4 +1,19 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - VIDEO STREAMING & SOCRATIC PLAYBACK CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: VideoController.php
+ * الهدف المعماري:
+ * إدارة منظومة بث الفيديو الرقمي، وتوليد الفحوصات السقراطية، وبث HLS المجزأ عبر Cloudflare R2.
+ * يتولى هذا الملف المهام التالية:
+ * 1. رفع ملفات الفيديو المباشرة وتحويلها وتجزئتها إلى مقاطع HLS مشفرة لحماية الملكية الفكرية.
+ * 2. تشغيل التحليل السمعي-البصري بالذكاء الاصطناعي (AiVideoAnalyzerService) لتوليد الفصول الزمنية ونقاط الفحص السقراطي.
+ * 3. بث الفيديو عبر روابط مؤقتة آمنة (Byte-Range Streaming و HLS Playlists).
+ * 4. تزويد مشغل الفيديو في فلاتر ببيانات التشغيل (الروابط، الفصول، المعلم المعتمد، ونقاط التوقف السقراطية).
+ * 5. حفظ تقدم المشاهدة اللحظي لكل طالب في جدول (lesson_progress) وإدارة الاستئناف التلقائي.
+ */
 
 namespace App\Controllers;
 
@@ -13,8 +28,11 @@ use App\Services\CurriculumService;
 class VideoController
 {
     /**
-     * Upload Video directly via API, transcode HLS, and trigger Autonomous Gemini AI Analysis
+     * رفع فيديو الشرح مباشرة عبر واجهة البرمجة وتوليد HLS وبدء التحليل السقراطي بالذكاء الاصطناعي
      * POST /api/teacher/videos/upload-direct
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على ملف الفيديو والبيانات الوصفية
+     * @param Response $response كائن الاستجابة بحالة الرفع ومعرف الدرس ورابط المشاهدة
      */
     public function uploadDirect(Request $request, Response $response): void
     {