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

backend/app/Services/AiQuestionBankGeneratorService.php

@@ -1,20 +1,36 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AI QUESTION BANK GENERATOR SERVICE
+ * ==============================================================================
+ * 
+ * ملف: AiQuestionBankGeneratorService.php
+ * الهدف المعماري:
+ * المحرك المركزي العام لتوليد وفهرسة بنوك الأسئلة الوزارية والتكيفية بالذكاء الاصطناعي.
+ * مصمم ليكون مستقلاً تماماً عن الصف أو المادة:
+ * 1. يقرأ ملفات المناهج بصيغة Markdown المرفوعة على السيرفر لأي كتاب أو وحدة أو درس.
+ * 2. يحلل المحتوى والنتاجات والمعادلات عبر Gemini API بواسطة برومبت قياس وتقويم وزاري محكم.
+ * 3. يولد 50 سؤالاً مصنفاً لكل وحدة، و 15-20 سؤالاً لكل درس، مصنفة حسب هرمية بلوم (تذكر، فهم، تطبيق، تحليل).
+ * 4. يربط كل سؤال بوسمه الموضوعي (topic_tag) والشرح العلمي والخيارات والتغذية الراجعة.
+ * 5. يوفر محرك توليد احتياطي حتمي (Deterministic Curriculum Synthesis) مبني على نصوص وتمارين الكتاب
+ *    ليعمل النظام بكفاءة 100% حتى في حال غياب أو تعطل مفتاح Gemini الخارجي.
+ * 6. يحقن الأسئلة مباشرة في جدولي (questions) و (question_options) في قاعدة بيانات صَقِل.
+ */
 
 namespace App\Services;
 
 use App\Core\Database;
 use App\Core\Env;
 
-/**
- * Universal Server-Side AI Question Bank Generator Service
- * Ingests Curriculum Markdown Files (for any Grade / Subject) and generates:
- * 1. 15-20 Questions per Lesson (tagged with bloom_taxonomy, topic_tag, and difficulty)
- * 2. 50 Comprehensive Questions per Unit (seeded into Question Bank for Adaptive Testing)
- */
 class AiQuestionBankGeneratorService
 {
     /**
-     * Generate 50 Comprehensive Questions for a Unit from its Markdown files
+     * توليد وحقن بنك الـ 50 سؤالاً الشامل للوحدة الدراسية من ملفات الماركداون
+     * 
+     * @param string $unitRelativePath المسار النسبي لمجلد الوحدة داخل storage/curriculum
+     * @param int    $courseId         معرّف المادة الدراسية
+     * @param int    $targetCount      العدد المستهدف من الأسئلة في البنك (افتراضياً 50)
+     * @return array مصفوفة تحتوي على معرف الامتحان وعنوان الوحدة وإجمالي الأسئلة المحقونة
      */
     public static function generateUnitQuestionBank(string $unitRelativePath, int $courseId = 1, int $targetCount = 50): array
     {