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

backend/app/Services/AiLessonEnhancerService.php

@@ -1,4 +1,18 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AI LESSON ASSETS ENHANCER SERVICE
+ * ==============================================================================
+ * 
+ * ملف: AiLessonEnhancerService.php
+ * الهدف المعماري:
+ * توليد وتطوير الأصول التعليمية الذكية للدروس والمناهج:
+ * 1. تحويل نص الماركداون للدرس إلى ملخص مركز (Cheat Sheet) وقواعد ذهبية.
+ * 2. صياغة سيناريو حواري لشرح الدرس (Video Script).
+ * 3. توليد سؤال فحص سقراطي ذكي مع خيارات وشرح علمي.
+ * 4. توليد برومبتات المحاكيات الفيزيائية والمعامل التفاعلية (HTML5 Canvas Interactive Lab Simulations).
+ * 5. يوفر آلية توليد احتياطية حتمية تضمن الاستقرار الدائم.
+ */
 
 namespace App\Services;
 
@@ -8,7 +22,11 @@ use App\Core\Env;
 class AiLessonEnhancerService
 {
     /**
-     * Extracts the lively script, cheat sheet, and Socratic quiz using Gemini or Intelligent Synthesis Fallback.
+     * استخراج المخرجات الذكية (الملخص، الفحص السقراطي، والسيناريو) من نص الدرس
+     * 
+     * @param string $title   عنوان الدرس
+     * @param string $content محتوى الدرس بصيغة الماركداون
+     * @return array مصفوفة تحتوي على cheat_sheet, socratic_quiz, video_script
      */
     public static function generateFromText(string $title, string $content): array
     {