FIR resolve: add minor comments about substitutions around JvmMappedScope

compiler/fir/resolve/src/org/jetbrains/kotlin/fir/resolve/FirSymbolProvider.kt

@@ -77,7 +77,8 @@ abstract class FirSymbolProvider : FirSessionComponent {
                 if (klass !is FirRegularClass) {
                     jvmMappedScope
                 } else {
-                    // We should substitute Java type parameters with base Kotlin type parameters to match overrides perfectly
+                    // We should substitute Java type parameters with base Kotlin type parameters to match overrides properly
+                    // It's necessary for MutableMap, which has *two* JavaMappedScope inside (one for itself and another for base Map)
                     (klass.symbol.constructType(
                         klass.typeParameters.map { ConeTypeParameterTypeImpl(it.symbol.toLookupTag(), false) }.toTypedArray(),
                         false

compiler/fir/resolve/src/org/jetbrains/kotlin/fir/resolve/SupertypeUtils.kt

@@ -108,6 +108,9 @@ fun ConeClassLikeType.wrapSubstitutionScopeIfNeed(
         val javaClassId = JavaToKotlinClassMap.mapKotlinToJava(declaration.symbol.classId.asSingleFqName().toUnsafe())
         val javaClass = javaClassId?.let { session.firSymbolProvider.getClassLikeSymbolByFqName(it)?.fir } as? FirRegularClass
         if (javaClass != null) {
+            // This kind of substitution is necessary when method which is mapped from Java (e.g. Java Map.forEach)
+            // is called on an external type, like MyMap<String, String>,
+            // to determine parameter types properly (e.g. String, String instead of K, V)
             val javaTypeParameters = javaClass.typeParameters
             val javaSubstitution = createSubstitution(javaTypeParameters, typeArguments, session)
             FirClassSubstitutionScope(session, useSiteMemberScope, builder, originalSubstitution + javaSubstitution)